feat(mesh): bind dispatcher runs to agent turns - #11252

✅ Qwen Triage finished — view run. See the stage comments in this thread for the result.

✅ Qwen Triage 已完成 —— 查看运行。结果见本线程中的各阶段评论。

No admission decision — this PR merged before triage ran

Timeline, from the API:

• 04:03:52Z — PR opened
• 04:04:00Z — merged by @yiliang114 (admin), 8 seconds later
• 04:08:06Z — triage posted its "running" lifecycle comment, 4 minutes after the merge

So there was nothing to gate. I am not issuing an approval or a request-changes here: on merged code an approval is a no-op and a request-changes cannot be acted on, and either would read as an admission verdict that was never actually available. The stages below are what I could still establish, because this commit reaches main through the open parent delivery PR #11206 (codex/multi-agent-mesh-foundation, 83 files) — that PR is where the gate properly applies.

Gate facts (Stage 0 / guardrails). All 17 files are core paths, so the two-tier core gate is in scope by path. It does not bite: the title is feat, which is never hard-blocked on size, and production logic lines come to ~463 (506 total − 26 in dispatch-port.test.ts − 17 in the two docs/plans files), under the 500-line maintainer-awareness trigger and well under the 1000+ advisory. The author has admin, so the change is maintainer-authored and exempt from the gate regardless. Not a fork and not a refactor, so the fork-refactor approval guardrail does not apply either.

Test evidence: none exists, and I want to be blunt about that. There are zero pull_request workflow runs on 0a807ff7d1dfd5563c19736482742552cb3d496c. Every check-run on that SHA is pull_request_target bot orchestration — precheck-pr, review-pr, tmux-testing, verify and friends, all skipped or cancelled, plus this triage run still in progress. No build, no typecheck, no lint, no unit suite ever executed against this head; the merge beat CI to it. That lines up with the PR's own words — "Tested on: macOS ⚠️ Not run locally" — and with the acceptance doc this diff edits, which says the correction "was deliberately not expanded with new test code or a local CI/build pass". Per the gate's rules I did not build or run anything myself. So the honest status is: not verified — no automated evidence exists for this commit on any platform. The one test touched, dispatch-port.test.ts, was never executed here.

What I could verify statically (reading the merge-commit tree, not running it). The central mechanism is sound, and better than I expected before reading it:

• Tool visibility actually works. prepareTools() computes getExcludedToolsForCurrentContext() at agent-core.ts:683, and that call sits inside the agent's own AsyncLocalStorage frame, which runMeshTurn → runWithMeshRunContext establishes around bgBody. So the six thread_* tools really are un-excluded for a mesh turn and stay hidden for ordinary subagents and teammates.
• runWithMeshRunContext throws on nesting a different run and permits re-entering an identical one. That is the right failure shape — it makes "body bound to its first thread forever" impossible rather than merely unlikely.
• registry.continueResidentAgent(agentId, message, deliveryId?) already takes the third argument on the base, so the new call site is not a signature break.
• finishRun in the bridge's finally block does fix the "successful work left permanently running" problem the PR set out to solve, and a non-terminal meta status becomes failed rather than an implicit success.

One finding worth carrying into #11206 — the binding is persisted before the dispatch is known to succeed. In dispatch-port.ts, start() calls bindNextTurn() before the action switch for every non-launch action, and bindNextTurn writes meshRun into the body's meta file. But the switch can still fail afterwards: continue_completed can return capacity_wait, not_completed can fail its revive into launch_failed, and resume can fail the same way. In each case the dispatcher releases the claim without spending the attempt — yet the stale meshRun for a run that never started stays on disk.

The reason this is not merely untidy: finishRunInTransaction treats queued as a finishable status (run-lifecycle.ts:398-402), so it will terminalize a released run silently rather than throwing. Any later turn on that resident body which reaches readAgentMeta(metaPath)?.meshRun without first passing through bindNextTurn would expose the thread tools to a non-mesh turn and, at turn end, close out a run that was never executed — recording closeKind: 'unclosed' or a failure against it. A subsequent mesh dispatch does rebind and overwrite, so this needs a turn that starts outside the dispatch port; I could not establish from the diff whether such a path exists for a mesh body, and I am flagging it as an open reachability question rather than asserting a live bug. Binding after the action succeeds — or rolling the binding back on any non-started result — would close it either way, and would also match the fail-loud posture the rest of the mesh code deliberately takes.

Minor, non-blocking. The six thread-tool names are now enumerated in five places: MESH_THREAD_TOOL_NAMES and MESH_TOOL_CLASSIFICATION in capability.ts, MESH_THREAD_TOOLS plus the two EXCLUDED_TOOLS_FOR_* sets in agent-core.ts. Moving capability.ts off string literals onto ToolNames.* is a genuine improvement this PR made; deriving the agent-core.ts list from the existing MESH_THREAD_TOOL_NAMES export would remove the remaining duplication so a seventh tool cannot be added to four of the five.

On direction and scope. Nothing to raise. This is the minimum seam the stated goal needs — no speculative recovery, cancellation, REST or Web Shell surface, all of which the PR explicitly puts out of scope. The isolation argument holds: ordinary subagents keep the tools hidden, and the coupling stays inside agents/mesh/ plus two small, additive registrations in config.ts and rule-parser.ts. My independent proposal before reading the diff was essentially this shape, and I expected the mesh concept to leak further into general-purpose config and permissions than it did.

Suggest the two items above — the binding-order question and a first automated pass — get picked up on #11206, where there is still a gate to satisfy and CI will actually run.

— Qwen Code · qwen3.8-max-2026-09-02

_{Reviewed at 0a807ff7d1dfd5563c19736482742552cb3d496c · re-run with @qwen-code /triage}